home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / Translation.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  12KB  |  314 lines
  1. /*
  2.      File:        Translation.h
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __TRANSLATION__
  19. #define __TRANSLATION__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __FILES__
  25. #include <Files.h>
  26. #endif
  27. #ifndef __COMPONENTS__
  28. #include <Components.h>
  29. #endif
  30. #ifndef __TRANSLATIONEXTENSIONS__
  31. #include <TranslationExtensions.h>
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. #if PRAGMA_IMPORT_SUPPORTED
  39. #pragma import on
  40. #endif
  41.  
  42. #if PRAGMA_ALIGN_SUPPORTED
  43. #pragma options align=mac68k
  44. #endif
  45.  
  46. /* enumerated types on how a document can be opened*/
  47. typedef short DocOpenMethod;
  48.  
  49. enum {
  50.     domCannot                    = 0,
  51.     domNative                    = 1,
  52.     domTranslateFirst            = 2,
  53.     domWildcard                    = 3
  54. };
  55.  
  56. /* 0L terminated array of OSTypes, or FileTypes*/
  57. typedef OSType TypesBlock[64];
  58. typedef OSType *TypesBlockPtr;
  59. /* Progress dialog resource ID*/
  60.  
  61. enum {
  62.     kTranslationScrapProgressDialogID = -16555
  63. };
  64.  
  65. /* block of data that describes how to translate*/
  66. struct FileTranslationSpec {
  67.     OSType                             componentSignature;
  68.     const void *                    translationSystemInfo;
  69.     FileTypeSpec                     src;
  70.     FileTypeSpec                     dst;
  71. };
  72. typedef struct FileTranslationSpec FileTranslationSpec;
  73.  
  74. typedef FileTranslationSpec *FileTranslationSpecArrayPtr;
  75. #if FOR_SYSTEM7_AND_SYSTEM8_COOPERATIVE
  76. /*
  77. ****************************************************************************************
  78. * 
  79. *   GetFileTypesThatAppCanNativelyOpen
  80. * 
  81. *  This routine returns a list of all FileTypes that an application can open by itself
  82. * 
  83. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  84. *             appSignature        signature (creator) of application
  85. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  86. * 
  87. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  88. */
  89. extern pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  90.  TWOWORDINLINE(0x701C, 0xABFC);
  91.  
  92. /*
  93. ****************************************************************************************
  94. * 
  95. *  ExtendFileTypeList
  96. * 
  97. *  This routine makes a new list of file types that can be translated into a type in the given list
  98. *  Used by StandardFile
  99. * 
  100. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  101. *             numberOriginalTypes        number of file types in orgTypeList
  102. *              extendedTypeList        pointer to a buffer to be filled with file types
  103. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  104. * 
  105. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  106. *             numberExtendedTypes        number of file types put in extendedTypeList
  107. */
  108. extern pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  109.  TWOWORDINLINE(0x7009, 0xABFC);
  110.  
  111. /*
  112. ****************************************************************************************
  113. * 
  114. * 
  115. *  This routine checks if a file can be opened by a particular application.
  116. *  If so, it returns if it needs to be translated first, and if so then how.
  117. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  118. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  119. * 
  120. *  Enter:    targetDocument        document to check if it can be opened
  121. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  122. *             appSignature        signature (creator) of application to open doc
  123. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  124. *             onlyNative            whether to consider if document can be translated before opening
  125. *             howToOpen            pointer to buffer in which to put how the document can be opened
  126. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  127. * 
  128. *  Exit:    howToOpen            whether file needs to be translated to be read
  129. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  130. *             returns                noErr, noPrefAppErr
  131. */
  132. extern pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  133.  TWOWORDINLINE(0x701E, 0xABFC);
  134.  
  135. /*
  136. ****************************************************************************************
  137. * 
  138. *  GetFileTranslationPaths
  139. * 
  140. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  141. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  142. * 
  143. *  Enter:    srcDoc            source file or NULL for all matches
  144. *             dstDoc            destination FileType or NULL for all matches
  145. *             maxResultCount
  146. *             resultBuffer
  147. *  Exit:    number of paths
  148. */
  149. extern pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  150.  TWOWORDINLINE(0x7038, 0xABFC);
  151.  
  152. /*
  153. ****************************************************************************************
  154. * 
  155. *  GetPathFromTranslationDialog
  156. * 
  157. *  This routine, with a given document, application, and a passed typelist will display the
  158. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  159. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  160. *  The routine returns the translation path information.
  161. * 
  162. *  Enter:    theDocument            FSSpec to document to open
  163. *             theApplication        FSSpec to application to open document
  164. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  165. *                                 you would like the documented translated to.  Order most perferred
  166. *                                 to least.
  167. * 
  168. *  Exit:    howToOpen            Translation method needed to open document
  169. *             howToTranslate        Translation specification
  170. *             returns                Any errors that might occur.
  171. */
  172. extern pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  173.  TWOWORDINLINE(0x7037, 0xABFC);
  174.  
  175. /*
  176. ****************************************************************************************
  177. * 
  178. *   TranslateFile
  179. * 
  180. *  This routine reads a file of one format and writes it to another file in another format. 
  181. *  The information on how to translated is generated by the routine CanDocBeOpened.
  182. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  183. *  The destination file must not exist.  It is created by this routine.  
  184. * 
  185. *  Enter:    sourceDocument            input file to translate
  186. *             destinationDocument        output file of translation
  187. *             howToTranslate            pointer to info on how to translate
  188. *  Exit:    returns                    noErr, badTranslationSpecErr 
  189. */
  190. extern pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  191.  TWOWORDINLINE(0x700C, 0xABFC);
  192.  
  193. /*
  194. ****************************************************************************************
  195. * 
  196. *   GetDocumentKindString
  197. * 
  198. *  This routine returns the string the Finder should show for the "kind" of a document
  199. *  in the GetInfo window and in the kind column of a list view.  
  200. * 
  201. *  Enter:    docVRefNum        The volume containing the document
  202. *             docType            The catInfo.fdType of the document
  203. *             docCreator        The catInfo.fdCreator of the document
  204. *             kindString        pointer to where to return the string
  205. * 
  206. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  207. *             returns            noErr, or afpItemNoFound if kind could not be determined
  208. */
  209. extern pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  210.  TWOWORDINLINE(0x7016, 0xABFC);
  211.  
  212. /*
  213. ****************************************************************************************
  214. * 
  215. *  GetTranslationExtensionName
  216. * 
  217. *  This routine returns the translation system name from a specified TranslationSpec
  218. * 
  219. *  Enter:    translationMethod    The translation path to get the translation name from
  220. * 
  221. *  Exit:    extensionName        The name of the translation system
  222. *             returns                Any errors that might occur
  223. */
  224. extern pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  225.  TWOWORDINLINE(0x7036, 0xABFC);
  226.  
  227. /*
  228. ****************************************************************************************
  229. * 
  230. *  GetScrapDataProcPtr
  231. * 
  232. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  233. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  234. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  235. *  with a list all the formats that you have available to be translated, and the length of each.
  236. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  237. *  the formats that 'fmts' list said was available.
  238. * 
  239. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  240. *             dataH                    Handle in which to put the requested data
  241. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  242. *             
  243. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  244. */
  245. typedef pascal OSErr (*GetScrapDataProcPtr)(ScrapType requestedFormat, Handle dataH, void *srcDataGetterRefCon);
  246.  
  247. #if GENERATINGCFM
  248. typedef UniversalProcPtr GetScrapDataUPP;
  249. #else
  250. typedef GetScrapDataProcPtr GetScrapDataUPP;
  251. #endif
  252.  
  253. enum {
  254.     uppGetScrapDataProcInfo = kPascalStackBased
  255.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  256.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ScrapType)))
  257.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(Handle)))
  258.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(void *)))
  259. };
  260.  
  261. #if GENERATINGCFM
  262. #define NewGetScrapDataProc(userRoutine)        \
  263.         (GetScrapDataUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppGetScrapDataProcInfo, GetCurrentArchitecture())
  264. #else
  265. #define NewGetScrapDataProc(userRoutine)        \
  266.         ((GetScrapDataUPP) (userRoutine))
  267. #endif
  268.  
  269. #if GENERATINGCFM
  270. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  271.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppGetScrapDataProcInfo, (requestedFormat), (dataH), (srcDataGetterRefCon))
  272. #else
  273. #define CallGetScrapDataProc(userRoutine, requestedFormat, dataH, srcDataGetterRefCon)        \
  274.         (*(userRoutine))((requestedFormat), (dataH), (srcDataGetterRefCon))
  275. #endif
  276. typedef GetScrapDataUPP GetScrapData;
  277. /*
  278. ****************************************************************************************
  279. * 
  280. *  TranslateScrap
  281. * 
  282. *  This routine resizes the destination handle and fills it with data of the requested format.
  283. *  The data is generated by translated one or more source formats of data supplied by
  284. *  the procedure srcDataGetter.  
  285. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  286. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  287. * 
  288. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  289. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  290. *             destinationFormat            Format of data desired
  291. *             destinationData                Handle in which to store translated data
  292. *             
  293. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  294. */
  295. extern pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  296.  TWOWORDINLINE(0x700E, 0xABFC);
  297.  
  298. #endif
  299.  
  300. #if PRAGMA_ALIGN_SUPPORTED
  301. #pragma options align=reset
  302. #endif
  303.  
  304. #if PRAGMA_IMPORT_SUPPORTED
  305. #pragma import off
  306. #endif
  307.  
  308. #ifdef __cplusplus
  309. }
  310. #endif
  311.  
  312. #endif /* __TRANSLATION__ */
  313.  
  314.